home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Choice.java < prev    next >
Text File  |  1998-09-22  |  14KB  |  455 lines
  1. /*
  2.  * @(#)Choice.java    1.48 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.util.*;
  17. import java.awt.peer.ChoicePeer;
  18. import java.awt.event.*;
  19. import java.io.ObjectOutputStream;
  20. import java.io.ObjectInputStream;
  21. import java.io.IOException;
  22.  
  23.  
  24. /**
  25.  * The <code>Choice</code> class presents a pop-up menu of choices. 
  26.  * The current choice is displayed as the title of the menu. 
  27.  * <p>
  28.  * The following code example produces a pop-up menu: 
  29.  * <p>
  30.  * <hr><blockquote><pre>
  31.  * Choice ColorChooser = new Choice();
  32.  * ColorChooser.add("Green");
  33.  * ColorChooser.add("Red");
  34.  * ColorChooser.add("Blue");
  35.  * </pre></blockquote><hr>
  36.  * <p>
  37.  * After this choice menu has been added to a panel, 
  38.  * it appears as follows in its normal state:
  39.  * <p>
  40.  * <img src="images-awt/Choice-1.gif"
  41.  * ALIGN=center HSPACE=10 VSPACE=7> 
  42.  * <p>
  43.  * In the picture, <code>"Green"</code> is the current choice. 
  44.  * Pushing the mouse button down on the object causes a menu to 
  45.  * appear with the current choice highlighted. 
  46.  * <p>
  47.  * @version    1.48 07/01/98
  48.  * @author     Sami Shaio
  49.  * @author     Arthur van Hoff
  50.  * @since       JDK1.0
  51.  */
  52. public class Choice extends Component implements ItemSelectable {
  53.     /**
  54.      * The items for the Choice.
  55.      */
  56.     Vector pItems;
  57.  
  58.     /** 
  59.      * The index of the current choice for this Choice.
  60.      */
  61.     int selectedIndex = -1;
  62.  
  63.     transient ItemListener itemListener;
  64.  
  65.     private static final String base = "choice";
  66.     private static int nameCounter = 0;
  67.  
  68.     /*
  69.      * JDK 1.1 serialVersionUID 
  70.      */
  71.      private static final long serialVersionUID = -4075310674757313071L;
  72.  
  73.     /** 
  74.      * Creates a new choice menu. The menu initially has no items in it. 
  75.      * <p>
  76.      * By default, the first item added to the choice menu becomes the 
  77.      * selected item, until a different selection is made by the user  
  78.      * by calling one of the <code>select</code> methods. 
  79.      * @see       java.awt.Choice#select(int)
  80.      * @see       java.awt.Choice#select(java.lang.String)
  81.      * @since     JDK1.0
  82.      */
  83.     public Choice() {
  84.     pItems = new Vector();
  85.     }
  86.  
  87.     /**
  88.      * Construct a name for this component.  Called by getName() when the
  89.      * name is null.
  90.      */
  91.     String constructComponentName() {
  92.         return base + nameCounter++;
  93.     }
  94.  
  95.     /**
  96.      * Creates the Choice's peer.  This peer allows us to change the look
  97.      * of the Choice without changing its functionality.
  98.      * @see     java.awt.Toolkit#createChoice(java.awt.Choice)
  99.      * @see     java.awt.Component#getToolkit()
  100.      * @since   JDK1.0
  101.      */
  102.     public void addNotify() {
  103.         synchronized (getTreeLock()) {
  104.         if (peer == null)
  105.             peer = getToolkit().createChoice(this);
  106.         super.addNotify();
  107.         }
  108.     }
  109.  
  110.     /**
  111.      * Returns the number of items in this <code>Choice</code> menu.
  112.      * @see     java.awt.Choice#getItem
  113.      * @since   JDK1.1
  114.      */
  115.     public int getItemCount() {
  116.     return countItems();
  117.     }
  118.  
  119.     /**
  120.      * @deprecated As of JDK version 1.1,
  121.      * replaced by <code>getItemCount()</code>.
  122.      */
  123.     public int countItems() {
  124.     return pItems.size();
  125.     }
  126.  
  127.     /**
  128.      * Gets the string at the specified index in this 
  129.      * <code>Choice</code> menu.
  130.      * @param      index the index at which to begin.
  131.      * @see        java.awt.Choice#getItemCount
  132.      * @since      JDK1.0
  133.      */
  134.     public String getItem(int index) {
  135.     return (String)pItems.elementAt(index);
  136.     }
  137.  
  138.     /**
  139.      * Adds an item to this <code>Choice</code> menu.
  140.      * @param      item    the item to be added
  141.      * @exception  NullPointerException   if the item's value is <code>null</code>.
  142.      * @since      JDK1.1
  143.      */
  144.     public void add(String item) {
  145.     addItem(item);
  146.     }
  147.  
  148.     /**
  149.      * Adds an item to this Choice.
  150.      * @param item the item to be added
  151.      * @exception NullPointerException If the item's value is equal to null.
  152.      */
  153.     public synchronized void addItem(String item) {
  154.     if (item == null) {
  155.         throw new NullPointerException("cannot add null item to Choice");
  156.     }
  157.     pItems.addElement(item);
  158.     ChoicePeer peer = (ChoicePeer)this.peer;
  159.     if (peer != null) {
  160.         peer.addItem(item, pItems.size() - 1);
  161.     }
  162.     if (selectedIndex < 0) {
  163.         select(0);
  164.     }
  165.     }
  166.  
  167.  
  168.     /**
  169.      * Inserts the item into this choice at the specified position.
  170.      * @param item the item to be inserted
  171.      * @param index the position at which the item should be inserted
  172.      * @exception IllegalArgumentException if index is less than 0.
  173.      */
  174.  
  175.     public synchronized void insert(String item, int index) {
  176.     if (index < 0) {
  177.         throw new IllegalArgumentException("index less than zero.");
  178.     }
  179.  
  180.         int nitems = getItemCount();
  181.     Vector tempItems = new Vector();
  182.  
  183.     /* Remove the item at index, nitems-index times 
  184.        storing them in a temporary vector in the
  185.        order they appear on the choice menu.
  186.        */
  187.     for (int i = index ; i < nitems; i++) {
  188.         tempItems.addElement(getItem(index));
  189.         remove(index);
  190.     }
  191.  
  192.     add(item);
  193.  
  194.     /* Add the removed items back to the choice menu, they 
  195.        are already in the correct order in the temp vector.
  196.        */
  197.     for (int i = 0; i < tempItems.size()  ; i++) {
  198.         add((String)tempItems.elementAt(i));
  199.     }
  200.     }
  201.  
  202.     /**
  203.      * Remove the first occurrence of <code>item</code> 
  204.      * from the <code>Choice</code> menu.
  205.      * @param      item  the item to remove from this <code>Choice</code> menu.
  206.      * @exception  IllegalArgumentException  if the item doesn't 
  207.      *                     exist in the choice menu.
  208.      * @since      JDK1.1
  209.      */
  210.     public synchronized void remove(String item) {
  211.         int index = pItems.indexOf(item);
  212.         if (index < 0) {
  213.         throw new IllegalArgumentException("item " + item +
  214.                            " not found in choice");
  215.     } else {
  216.         remove(index);
  217.     }
  218.     }
  219.  
  220.     /**
  221.      * Removes an item from the choice menu 
  222.      * at the specified position.
  223.      * @param      position the position of the item.
  224.      * @since      JDK1.1
  225.      */
  226.     public synchronized void remove(int position) {
  227.         pItems.removeElementAt(position);
  228.         ChoicePeer peer = (ChoicePeer)this.peer;
  229.         if (peer != null) {
  230.         peer.remove(position);
  231.     }
  232.         /* Adjust selectedIndex if selected item was removed. */
  233.         if (pItems.size() == 0) {
  234.         selectedIndex = -1;
  235.     } else if (selectedIndex == position) {
  236.         select(0);
  237.     } else if (selectedIndex > position) {
  238.         select(selectedIndex-1);
  239.     }
  240.     }
  241.  
  242.     /**
  243.      * Removes all items from the choice menu.
  244.      * @see       java.awt.Choice#remove
  245.      * @since     JDK1.1
  246.      */
  247.     public synchronized void removeAll() {
  248.         int nitems = getItemCount();
  249.     for (int i = 0 ; i < nitems ; i++) {
  250.         remove(0);
  251.     }
  252.     }
  253.  
  254.     /**
  255.      * Gets a representation of the current choice as a string.
  256.      * @return    a string representation of the currently 
  257.      *                     selected item in this choice menu.
  258.      * @see       java.awt.Choice#getSelectedIndex
  259.      * @since     JDK1.0
  260.      */
  261.     public synchronized String getSelectedItem() {
  262.     return (selectedIndex >= 0) ? getItem(selectedIndex) : null;
  263.     }
  264.  
  265.     /**
  266.      * Returns an array (length 1) containing the currently selected
  267.      * item.  If this choice has no items, returns null.
  268.      * @see ItemSelectable
  269.      */
  270.     public synchronized Object[] getSelectedObjects() {
  271.     if (selectedIndex >= 0) {
  272.             Object[] items = new Object[1];
  273.             items[0] = getItem(selectedIndex);
  274.             return items;
  275.         }
  276.         return null;
  277.     }
  278.  
  279.     /**
  280.      * Returns the index of the currently selected item.
  281.      * @see #getSelectedItem
  282.      */
  283.     public int getSelectedIndex() {
  284.     return selectedIndex;
  285.     }
  286.  
  287.     /**
  288.      * Sets the selected item in this <code>Choice</code> menu to be the 
  289.      * item at the specified position. 
  290.      * @param      pos      the positon of the selected item.
  291.      * @exception  IllegalArgumentException if the specified
  292.      *                            position is invalid.
  293.      * @see        java.awt.Choice#getSelectedItem
  294.      * @see        java.awt.Choice#getSelectedIndex
  295.      * @since      JDK1.0
  296.      */
  297.     public void select(int pos) {
  298.     if (pos >= pItems.size()) {
  299.         throw new IllegalArgumentException("illegal Choice item position: " + pos);
  300.     }
  301.     if (pItems.size() > 0) {
  302.         selectedIndex = pos;
  303.         ChoicePeer peer = (ChoicePeer)this.peer;
  304.         if (peer != null) {
  305.         peer.select(pos);
  306.         }
  307.     }
  308.     }
  309.  
  310.     /**
  311.      * Sets the selected item in this <code>Choice</code> menu 
  312.      * to be the item whose name is equal to the specified string. 
  313.      * If more than one item matches (is equal to) the specified string, 
  314.      * the one with the smallest index is selected. 
  315.      * @param       str     the specified string
  316.      * @see         java.awt.Choice#getSelectedItem
  317.      * @see         java.awt.Choice#getSelectedIndex
  318.      * @since       JDK1.0
  319.      */
  320.     public synchronized void select(String str) {
  321.     int index = pItems.indexOf(str);
  322.     if (index >= 0) {
  323.         select(index);
  324.     }
  325.     }
  326.  
  327.     /**
  328.      * Adds the specified item listener to receive item events from
  329.      * this <code>Choice</code> menu.
  330.      * @param         l    the item listener.
  331.      * @see           java.awt.event.ItemEvent
  332.      * @see           java.awt.event.ItemListener
  333.      * @see           java.awt.Choice#removeItemListener
  334.      * @since         JDK1.1
  335.      */ 
  336.     public synchronized void addItemListener(ItemListener l) {
  337.         itemListener = AWTEventMulticaster.add(itemListener, l);
  338.         newEventsOnly = true;
  339.     }
  340.  
  341.     /**
  342.      * Removes the specified item listener so that it no longer receives 
  343.      * item events from this <code>Choice</code> menu. 
  344.      * @param         l    the item listener.
  345.      * @see           java.awt.event.ItemEvent
  346.      * @see           java.awt.event.ItemListener
  347.      * @see           java.awt.Choice#addItemListener
  348.      * @since         JDK1.1
  349.      */ 
  350.     public synchronized void removeItemListener(ItemListener l) {
  351.         itemListener = AWTEventMulticaster.remove(itemListener, l);
  352.     }
  353.  
  354.     // REMIND: remove when filtering is done at lower level
  355.     boolean eventEnabled(AWTEvent e) {
  356.         if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
  357.             if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
  358.                 itemListener != null) {
  359.                 return true;
  360.             } 
  361.             return false;
  362.         }
  363.         return super.eventEnabled(e);
  364.     }        
  365.  
  366.     /**
  367.      * Processes events on this choice. If the event is an 
  368.      * instance of <code>ItemEvent</code>, it invokes the 
  369.      * <code>processItemEvent</code> method. Otherwise, it calls its
  370.      * superclass's <code>processEvent</code> method.
  371.      * @param      e the event.
  372.      * @see        java.awt.event.ItemEvent
  373.      * @see        java.awt.Choice#processItemEvent
  374.      * @since      JDK1.1
  375.      */
  376.     protected void processEvent(AWTEvent e) {
  377.         if (e instanceof ItemEvent) {
  378.             processItemEvent((ItemEvent)e);
  379.             return;
  380.         }
  381.     super.processEvent(e);
  382.     }
  383.  
  384.     /** 
  385.      * Processes item events occurring on this <code>Choice</code> 
  386.      * menu by dispatching them to any registered 
  387.      * <code>ItemListener</code> objects. 
  388.      * <p>
  389.      * This method is not called unless item events are 
  390.      * enabled for this component. Item events are enabled 
  391.      * when one of the following occurs:
  392.      * <p><ul>
  393.      * <li>An <code>ItemListener</code> object is registered 
  394.      * via <code>addItemListener</code>.
  395.      * <li>Item events are enabled via <code>enableEvents</code>.
  396.      * </ul>
  397.      * @param       e the item event.
  398.      * @see         java.awt.event.ItemEvent
  399.      * @see         java.awt.event.ItemListener
  400.      * @see         java.awt.Choice#addItemListener
  401.      * @see         java.awt.Component#enableEvents
  402.      * @since       JDK1.1
  403.      */  
  404.     protected void processItemEvent(ItemEvent e) {
  405.         if (itemListener != null) {
  406.             itemListener.itemStateChanged(e);
  407.         }
  408.     }
  409.  
  410.     /**
  411.      * Returns the parameter string representing the state of this 
  412.      * choice menu. This string is useful for debugging. 
  413.      * @return    the parameter string of this <code>Choice</code> menu.
  414.      * @since     JDK1.0
  415.      */
  416.     protected String paramString() {
  417.     return super.paramString() + ",current=" + getSelectedItem();
  418.     }
  419.  
  420.  
  421.     /* Serialization support. 
  422.      */
  423.  
  424.     private int choiceSerializedDataVersion = 1;
  425.  
  426.  
  427.     private void writeObject(ObjectOutputStream s)
  428.       throws java.io.IOException 
  429.     {
  430.       s.defaultWriteObject();
  431.  
  432.       AWTEventMulticaster.save(s, itemListenerK, itemListener);
  433.       s.writeObject(null);
  434.     }
  435.  
  436.  
  437.     private void readObject(ObjectInputStream s)
  438.       throws ClassNotFoundException, IOException 
  439.     {
  440.       s.defaultReadObject();
  441.  
  442.       Object keyOrNull;
  443.       while(null != (keyOrNull = s.readObject())) {
  444.     String key = ((String)keyOrNull).intern();
  445.  
  446.     if (itemListenerK == key) 
  447.       addItemListener((ItemListener)(s.readObject()));
  448.  
  449.     else // skip value for unrecognized key
  450.       s.readObject();
  451.       }
  452.     }
  453.  
  454. }
  455.